/*
--------------------------------------------------------------------------------

Copyright 2004, 2008 Conexant Systems, Inc.

4000 MacArthur Blvd., Newport Beach, CA 92660 USA.

All Rights Reserved Worldwide.

Information Contained Herein is Proprietary to Conexant Systems, Inc.

--------------------------------------------------------------------------------
*/

#ifndef DC_AMALLOC_API_H
#define DC_AMALLOC_API_H

/* controversial include.  This implementation of this API are based on
   TX_BYTE_POOL.  A future implementation need not use the tx_api.h at all.
   Should any code using this API need to also include tx_api.h?  I don't
   think so, so I'm including it here.
*/

#include "tx_api.h"


#if 0  // don't do LAS API yet
//=============================================================================
//  LAS (Linear Address Space) API


// Each allocated region of linear address space is represented by a
// descriptor 
typedef struct dc_las_region_struct
{
    struct dc_las_region_struct *next;
    struct dc_las_region_struct *prev;
    void *base;
    unsigned long size;
    dc_dmb first_dmb;
} DC_LAS_REGION_t;


// consistent use of the LAS system can be checked in several ways
typedef enum
{
    DC_LAS_CHECK_NONE,
    DC_LAS_CHECK_NOREUSE,
    DC_LAS_CHECK_PERMIT_REUSE,
    DC_LAS_CHECK_STRICT
} DC_LAS_CHECK_MODE_t;  

// allocate a block of linear address space, and populate that address
// space with memory from the DMB pool
DC_RETURN_CODE dc_las_alloc(DC_LAS_REGION_t *lasr, 
                            unsigned long size, 
                            unsigned long alignment);

// mark a block as free for error checking purposes
DC_RETURN_CODE dc_las_free (DC_LAS_REGION_t *lasr,
                            DC_LAS_CHECK_MODE_t check);
 
// LAS can be freed to a previously remembered point by using a MARK
typedef struct dc_las_mark_struct
{
    struct dc_las_mark_struct *next;
    struct dc_las_mark_struct *prev;
    void *top;
} DC_LAS_MARK_t;

// notes current allocation depth for subsequent release
DC_RETURN_CODE dc_las_mark(DC_LAS_MARK_t *releasepoint); 

// release memory allocated since the corresponding mark
// check parameter control how thorough the checking and reporting should be
DC_RETURN_CODE dc_las_release(DC_LAS_MARK_t *releasepoint, 
                              DC_LAS_CHECK_MODE_t check);

#endif

//===========================================================================
// MALLOC/FREE API


// This defines an arena structure.  
typedef struct dc_am_arena_struct
{
    struct dc_am_arena_struct *next;
    TX_MUTEX mutex;
    char *name;
    void /*DC_AM_ARENA_CB_CONTROL_t*/ *cb_list;
    void /*DC_AM_ARENA_MEMORY_DESCRIPTOR_t*/ *pool_list;
} DC_AM_ARENA_t;


// reasons why the callback functions may be called
typedef enum
{
    DC_AM_ARENA_CB_INITIALIZING,
    DC_AM_ARENA_CB_OOS_LEVEL_0,
    DC_AM_ARENA_CB_OOS_LEVEL_1,
    DC_AM_ARENA_CB_OOS_LEVEL_2,
    DC_AM_ARENA_CB_OOS_LEVEL_3,
    DC_AM_ARENA_CB_OOS_LEVEL_4,
    DC_AM_ARENA_CB_OOS_LEVEL_5,
    DC_AM_ARENA_CB_OOS_LEVEL_6,
    DC_AM_ARENA_CB_OOS_LEVEL_7,
    DC_AM_ARENA_CB_OOS_LEVEL_8,
    DC_AM_ARENA_CB_OOS_LEVEL_9,
    DC_AM_ARENA_CB_OOS_LAST_CALL,
    DC_AM_ARENA_CB_REMOVED,
    DC_AM_ARENA_CB_ENDING
} DC_AM_ARENA_CB_REASON_t;

// Type for the callback function
typedef DC_RETURN_CODE DC_AM_ARENA_CB_t(DC_AM_ARENA_t *arena,
                                           DC_AM_ARENA_CB_REASON_t reason,
                                           unsigned long arg);

// Type of object which records the existence of the callback
typedef struct dc_am_arena_cb_control_struct
{
    struct dc_am_arena_cb_control_struct *next;
    struct dc_am_arena_struct *arena;
    DC_AM_ARENA_CB_t *cb_fun;
    unsigned int cb_arg;
} DC_AM_ARENA_CB_CONTROL_t;


// Add a callback function to an arena
DC_RETURN_CODE dc_arena_cb_add(DC_AM_ARENA_t *arena,
                               DC_AM_ARENA_CB_CONTROL_t *cbc,
                               DC_AM_ARENA_CB_t *cb_fcn,
                               unsigned int cb_arg);

// Remove a callback function from an arena
DC_RETURN_CODE dc_arena_cb_remove(DC_AM_ARENA_t *arena,
                                  DC_AM_ARENA_CB_CONTROL_t *cbc);

// initialize arena with no storage.
DC_RETURN_CODE dc_am_arena_create(DC_AM_ARENA_t *arena, 
                                  char *name);

// each memory expansion block (including the first one) needs
// an arena memory descriptor block
typedef struct dc_am_arena_memory_descriptor_struct
{
    struct dc_am_arena_memory_descriptor_struct *next;
    DC_AM_ARENA_t *arena;
    TX_BYTE_POOL   byte_pool;
    void *base;
    unsigned long size;
}  DC_AM_ARENA_MEMORY_DESCRIPTOR_t;

// add a block of memory to an arena.  This may be called
// from the callback_fcn, or from user code.
// If the memdesc is NULL, space at the beginning of the
// new region will be used.
DC_RETURN_CODE dc_arena_expand(DC_AM_ARENA_t *arena,
                               DC_AM_ARENA_MEMORY_DESCRIPTOR_t *memdesc,
                               void *base,
                               unsigned long size);

// destroys the arena, but first calls the callback fcns if any.
DC_RETURN_CODE dc_arena_end(DC_AM_ARENA_t *arena);

// allocate size bytes, returning the resulting block in the
// location indicated by ptr.  If there is insufficient space,
// the arena callback_fcns are called.
DC_RETURN_CODE dc_am_malloc(DC_AM_ARENA_t *arena, 
                            void **ptr, 
                            unsigned long size);

DC_RETURN_CODE dc_am_realloc(DC_AM_ARENA_t *arena,
                             void **ptr,
                             unsigned long newsize);

DC_RETURN_CODE dc_am_calloc(DC_AM_ARENA_t *arena,
                            void **ptr,
                            unsigned long count,
                            unsigned long size);

// frees memory
DC_RETURN_CODE dc_am_free(DC_AM_ARENA_t *arena, void *ptr);



//==============================================================================
// Global arena functions -- to be used to set up a global pool, and perform
// conventional malloc/free functions.

extern DC_AM_ARENA_t dc__global_arena;

DC_RETURN_CODE dc_am_global_setup(UINT32 size);
void *dc_malloc(UINT32 size);
void *dc_realloc(void *ptr, UINT32 newsize);
void *dc_calloc(UINT32 count, UINT32 size);
void  dc_free(void *ptr);

#endif
